Getting Started - Simple Web Appplications

Introduction

This tutorial will show you how to get started using PicketBox in a simple web application.

This is the fastest way to get started. It is a very nice way to understand some basic concepts and how get things to work.

requisites

Maven Dependencies

<dependency>
    <groupId>org.picketbox</groupId>
    <artifactId>picketbox-http</artifactId>
    <version>${picketbox.version}</version>
</dependency>

Usage

Configuring the web.xml

PicketBox comes shipped with an important servlet filter called org.picketbox.http.filters.DelegatingSecurityFilter.

To enable PicketBox HTTP Security in your application the first thing you should do is define this filter in your web.xml. See the example bellow:

<!-- Configures FORM authentication scheme -->
<context-param>
    <param-name>org.picketbox.authentication</param-name>
    <param-value>FORM</param-value>
</context-param>

<!-- Custom ConfigurationBuilderProvider to provide a custom configuration using the Configuration API. -->
<context-param>
    <param-name>org.picketbox.configuration.provider</param-name>
    <param-value>org.picketbox.quickstarts.configuration.CustomConfigurationPovider</param-value>
</context-param>

<!-- Configures the PicketBox Security Filter -->
<filter>
    <filter-name>PicketBox Delegating Filter</filter-name>
    <filter-class>org.picketbox.http.filters.DelegatingSecurityFilter</filter-class>
</filter>

<!-- Configures all resources as protected by the PicketBox Security Filter -->
<filter-mapping>
    <filter-name>PicketBox Delegating Filter</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

As you can see, we defined two context parameters as following:

org.picketbox.authentication: This parameter defines which authentication scheme should be used. Possible values are FORM, BASIC, DIGEST and CLIENT_CERT. In our example we are using HTTP Form Authentication.
org.picketbox.configuration.provider: This parameter configures a org.picketbox.http.config.ConfigurationBuilderProvider implementation. The specified class will be used to produce the PicketBox configuration.

The code bellow shows how the org.picketbox.quickstarts.configuration.CustomConfigurationPovider class looks like:

public class CustomConfigurationPovider implements ConfigurationBuilderProvider {

    /*
     * (non-Javadoc)
     *
     * @see org.picketbox.http.config.ConfigurationBuilderProvider#getBuilder(javax.servlet.ServletContext)
     */
    @Override
    public HTTPConfigurationBuilder getBuilder(ServletContext servletcontext) {
        HTTPConfigurationBuilder configurationBuilder = new HTTPConfigurationBuilder();

        // protected resources configuration
        configurationBuilder.protectedResource()
                // unprotected resource. Usually this will be your application's static resources like CSS, JS, etc.
                .resource("/resources/*", ProtectedResourceConstraint.NOT_PROTECTED)

                // the login page is marked as not protected.
                .resource("/login.jsp", ProtectedResourceConstraint.NOT_PROTECTED)

                // the error page is marked as not protected.
                .resource("/error.jsp", ProtectedResourceConstraint.NOT_PROTECTED)

                // protected all resources. They will be available only for users with a role named 'guest'.
                .resource("/*", "guest");

        return configurationBuilder;
    }
}

Basically, we are configuring PicketBox to protected the application resources. Some resources like the login and error pages are not protected. For all other resources we are defining that they are allowed only for users with a role named guest.

You should always provide your own ConfigurationBuilderProvider implementation to configure the PicketBox behaviour. In the previous example we just configured the protected resource but there are some other configurations that you might find useful like:

Choose between the different Identity Store implementations (eg.: JPA and LDAP)
Session Management
Authorization using a built-in or specific Authorization Manager (eg.: drools-based authorization)
Event Handling to be notified about security events when an authentication is done or fail.
Auditing

For more information about the PicketBox configuration, check the Configuration API documentation.